GraphDemo previously only exercised the sequential/conditional-edge and
RequireApproval parts of Dext.AI.Graph, leaving two shipped primitives
completely unused anywhere in the repo: ICompiledAgent.AsNode and
TFileCheckpointer. Since the example is the reference for how to use the
framework, wire both in:

- Compile a small independent PolishGraph (single node, no tools) and
  embed it as the 'polish_agent' node of the main graph via
  PolishAgent.AsNode, routed to from call_llm's conditional edge instead
  of going straight to GRAPH_END. Its rewritten answer becomes the run's
  FinalAnswer by design (AsNode preserves FinalAnswer while clearing
  IsDone, so the parent's own edges decide what happens next).
- Switch the main checkpointer from TMemoryCheckpointer to
  TFileCheckpointer so the thread survives across process restarts, and
  print its path on startup.
- Add a ":estado" command to the input loop that calls Agent.GetState to
  inspect the persisted thread without running it.

Comment on the subgraph documents the one hard constraint: a subgraph
node can't itself use RequireApproval/InterruptBefore (AsNode raises
EGraphCompileError) - approval has to sit on the parent node that wraps
the subgraph call.

Compiles clean on Win32/Win64. Not yet live-tested against a real
OPENAI_API_KEY in this session - the polish_agent routing and FinalAnswer
override should be verified end-to-end before relying on it.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

Adds Docs/Book/16-ai-agents and its Docs/Book.pt-br mirror, following the
existing per-chapter README.md convention (see chapter 15 for MCP). Covers:
quick starts for both Dext.AI.Agent (single-agent ReAct, LangChain-style)
and Dext.AI.Graph (graph orchestration, LangGraph-style), the core type
table, human-in-the-loop, checkpointing, and subgraphs via AsNode - plus
an explicit LangGraph coverage table (what maps 1:1, what's a real gap:
no typed per-graph state schema, no conditional entry point, no
interrupt_after or dynamic interrupts, no update_state, no nested HITL,
no state history/time-travel, no cross-thread store, streaming only via
IAgentObserver callbacks, and a documented pitfall - a second AddEdge
from the same source node is silently ignored rather than fanning out).

Wires the new chapter into both Book/README.md and Book.pt-br/README.md
TOCs and example tables, and annotates Docs/roadmap/ai-roadmap.md to
point at what's actually implemented under the Dext.AI.Agent/Dext.AI.Graph
names, without rewriting the original Dext.SemanticKernel-branded roadmap
someone else wrote - just noting where the two now overlap.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

…in Dext.AI.Core.dpk

Addresses tier 2 from the PR dotpas#202 external review:

Collections (9 units):
- Dext.AI.Agent.Runner, Dext.AI.Agent.Provider.Anthropic,
  Dext.AI.Graph.Checkpointer/Compiled/Graph/State,
  Dext.AI.Graph.Node.Tools: swapped System.Generics.Collections for
  Dext.Collections (+ Dext.Collections.Dict / Dext.Collections.Queue where
  TDictionary/TQueue/TPair are used). TObjectList<T>.Create(True) became
  TList<T>.Create(True) - Dext.Collections merges ownership into TList
  itself rather than a separate TObjectList type. Verified the API shape
  first (constructors, TryGetValue/AddOrSetValue/ContainsKey, Enqueue/
  Dequeue, GetEnumerator) matches closely enough that this was a type-name
  swap, not a rewrite.
- Dext.AI.Agent.Provider.Ollama/OpenAI: System.Generics.Collections was
  imported but never actually used - dropped outright.
- Re-ran the standalone fake-provider harness (state propagation, HITL
  interrupt guard, error propagation) after the swap: still 7/7. Recompiled
  clean on Win32/Win64 for both GraphDemo and AgentDemo (a handful of
  H2443 hints about TJSONArray.GetValue losing inline expansion without
  System.Generics.Collections in the uses list - an RTL implementation
  detail of System.JSON itself, not a correctness issue, not worth
  reintroducing the RTL import for).

Package registration (32 files):
- Added all 15 Agent/Graph units to the `contains` clause of
  Dext.AI.Core.dpk and the matching <DCCReference> entries in
  Dext.AI.Core.dproj, across all 16 package variants (d11-d13, dberlin,
  drio, dseattle, dsydney, dtokyo, dxe2-dxe8) - confirmed byte-identical
  before editing, so the same block was safe to apply to all of them.
  Compiled Dext.AI.Core.dpk (d13) directly with dcc32 against the repo's
  existing Dext.Core.dcp/Dext.Web.Core.dcp: 0 errors, real .dcp/.bpl
  produced. The other 15 variants are the same mechanical edit against a
  package that already compiles those same units' dependencies (MCP) on
  all of them, but I don't have those Delphi versions installed to compile
  them myself - only d13 is compile-verified.

Not done: TAgentState's own allocation pattern (a new object + array/dict
clone per With* call) is unchanged - that's the tier-3 "real redesign"
item, not something a collections swap addresses.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

…collision, add Dext.AI.Graph test suite

Three of the four Tier 3 review items, each verified empirically (not just
compiled):

- LLM providers (OpenAI/Anthropic/Ollama) now use Dext.Net.RestClient
  instead of raw THTTPClient per call. Verified live against httpbin.org
  that both the 1-arg PostJson (OpenAI/Anthropic: full URL as BaseUrl) and
  2-arg PostJson (Ollama: BaseUrl + relative path) hit the exact expected
  URL with headers/body intact, before wiring them into the providers.
  Automatic retry was deliberately left off: retrying a POST that already
  reached the LLM but timed out on the response could double-call (and
  double-charge) it.

- TToolsNode and TAgentRunner now delegate tool registration/dispatch to
  Dext.AI.MCP.Tools.TMCPToolRegistry (already used by the MCP server)
  instead of each independently re-implementing the same RTTI scan over
  [MCPTool]/[MCPParam]. Ownership was the risk here — the registry takes
  ownership of registered providers — so this was checked for double-free
  via a real TMCPToolProvider descendant exercised end-to-end (register,
  list schemas, execute, unknown-tool path, dispose), not just compiled.

- Tests/AI/Graph/TestGraph.dpr: a Dext.Testing suite (15 tests) covering
  TAgentState.ToJson/FromJson round-trip, conditional edge routing,
  TFileCheckpointer.SanitizeId collision safety, human-in-the-loop
  (RequireApproval/Resume/Cancel/GetState), subgraph-as-node (AsNode) incl.
  the nested-HITL rejection and error propagation, and the
  TMCPToolRegistry adoption above. All 15 pass.

Also fixed a real bug this test-writing pass surfaced: TFileCheckpointer.
SanitizeId replaced invalid characters with "_", so e.g. thread ids "a/b"
and "a:b" both collapsed to the same "a_b" checkpoint file — one thread's
state could silently overwrite another's. Now appends a hash of the
original id to the sanitized name.

Dext.AI.Core.dpk (all 16 package variants) now requires Dext.Net.Core, and
AgentDemo/GraphDemo.dproj gained Sources\Net on their search path — both
mechanical, needed for the RestClient adoption. As with prior tiers, only
the d13 variant was actually compiled here (no other Delphi versions
installed in this environment); the other 15 got the identical mechanical
edit, unverified.

Deliberately NOT done: TAgentState's per-step allocation (record instead
of class, or similar). The review's ask doesn't buy what it claims —
class-to-record doesn't touch the actual cost driver (Copy() of the
messages array and metadata dictionary on every With* call), and it would
break TNodeHandler's already-shipped, already-documented signature across
GraphDemo, AgentDemo, and the Book chapter 16 samples in both languages.
Recommending against it in the PR thread rather than implementing it.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Sonnet 5 <[email protected]>

…nDataObjects

Replaces the RTL's System.JSON (TJSONObject/TJSONArray, AddPair/GetValue<T>)
with Dext's own DextJsonDataObjects (Sources/Core/Json) — an in-framework
fork of the well-known JsonDataObjects, indexer-based (Obj.S['key'] instead
of AddPair) and considerably faster on both parse and build than
System.JSON. Follows the same "use the framework's own library" pattern as
the Dext.Collections/Dext.Net.RestClient adoptions.

Made BuildRequestBody/ParseResponse public on all three providers (were
private) specifically so this could be verified with real unit tests
instead of just a compile check — Tests/AI/Agent/TestAgent.dpr, 15 tests
using response fixtures shaped like the real OpenAI/Anthropic/Ollama APIs
(including tool_calls/tool_use and the null-content-with-tool-calls case).

That test-writing pass caught two real behavioral differences from
System.JSON that a compile-only migration would have shipped silently:

- TJsonBaseObject.Parse raises EJsonParserException on syntactically
  invalid JSON instead of returning nil like System.JSON's
  ParseJSONValue — the "invalid response" error path in all three
  ParseResponse methods needed a try/except to keep surfacing
  ELLMProviderError instead of leaking the parser's own exception type.

- The parser represents a JSON `null` internally as jdtObject with a nil
  pointer, not a distinct "none" type — so Message.S['content'] threw
  EJsonCastException ("Cannot cast Object into String") on exactly the
  case that matters most here: OpenAI/Ollama responses where content is
  null because the model returned only tool_calls. Fixed by checking
  Types['content'] = jdtString before reading it as a string in both
  providers (Anthropic's content is always an array, unaffected).

Dext.AI.Agent.Runner.pas and the Graph/MCP units (Node.Tools.pas,
Graph.State.pas) still use System.JSON — out of scope for this pass, which
was scoped to the 3 providers specifically.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

Completes the JSON library migration started with the 3 LLM providers,
covering the remaining Dext.AI.* surface: Dext.AI.MCP.Types/Protocol/
Tools/Resources/Prompts/Server, Dext.AI.Agent.Runner, and
Dext.AI.Graph.State (checkpoint persistence).

BREAKING for MCP tool authors: TMCPToolCallback, TMCPToolResultCallback
and TMCPPromptGetCallback now take DextJsonDataObjects.TJsonObject
instead of System.JSON.TJSONObject. Since the type names are identical
(Pascal is case-insensitive), existing tool bodies compile against the
new type but their GetValue<T>/AddPair calls must be rewritten using
the new indexer API (Args.S['x'], Args.I['x'], etc. - no generic
GetValue<T> or fluent AddPair exists on the new type). Updated
GraphDemo, AgentDemo, MCP.FullDemo, and MCP.VclDbDemo accordingly.

The JSON-RPC "id" (string | number | null) is represented as a
standalone TJsonDataValueHelper in TJsonRpc.Success/Error/GetId, since
DextJsonDataObjects has no loose polymorphic value class equivalent to
System.JSON's TJSONValue. Added Tests/AI/MCP/TestMCP.Server.pas (8
tests) exercising TMCPServer.Dispatch directly - now public - to catch
any regression in the id round-trip (numeric vs string, notification
vs error-with-id), since Dext.AI.MCP.Server had no prior test coverage.

Verified: Dext.AI.Core.dpk (d13), TestGraph (15/15), TestAgent (15/15),
TestMCP (8/8), GraphDemo, AgentDemo, MCP.FullDemo, and MCP.VclDbDemo
all compile clean and the full test suite passes.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

TMemoryCheckpointer and TFileCheckpointer gain a TCriticalSection
guarding Save/Load/Exists/Delete - Dext.Collections' TDictionary isn't
thread-safe on its own, and MCP tool/HTTP handlers routinely call into
the same checkpointer from multiple worker threads.

TFileCheckpointer.Save now writes to a uniquely-named temp file and
replaces the final file (delete-then-move) instead of writing the
destination path directly, so a crash mid-write or a concurrent save
never leaves a truncated or interleaved checkpoint on disk. Does not
coordinate across separate OS processes sharing the same base path -
only within-process concurrency is addressed.

Replaced the three placeholder interface GUIDs in Dext.AI.MCP.Tools,
.Resources and .Prompts (IMCPToolBuilder, IMCPResourceBuilder,
IMCPPromptBuilder) with real generated ones.

Verified: Dext.AI.Core.dpk (d13), TestGraph (15/15 incl.
TFileCheckpointer.SaveLoadExistsDelete_RoundTrip), TestAgent (15/15),
TestMCP (8/8) all compile clean and pass.

Co-Authored-By: Claude Sonnet 5 <[email protected]>

…cted

AddEdge/AddConditionalEdge now reject a second edge from the same
source node at definition time (EGraphCompileError). ResolveNextNode
always picks the first edge whose SourceNode matches - a second AddEdge
from the same node was previously accepted silently and just never
taken at runtime.

Renamed ECycleDetected to ENoPathToEnd (now a subclass of
EGraphCompileError, matching every other graph-shape validation). The
check it guards never detected cycles - it verifies that at least one
path from the entry point reaches GRAPH_END, which is a different and
correct thing to require in a framework where cycles are the normal
ReAct pattern (call_llm -> execute_tools -> call_llm). The old name
just described the wrong failure mode.

Added TGraphValidationTests (4 tests) covering both: the two new
compile-time rejections, that a closed cycle with no exit raises
ENoPathToEnd, and - the important negative case - that the real
ReAct-style cycle (BuildToolLoopGraph) still compiles without error.

Verified: Dext.AI.Core.dpk (d13), TestGraph (19/19), GraphDemo all
compile clean; GraphDemo's own call_llm/execute_tools cycle is
unaffected by the dedup check since each node still has exactly one
outgoing edge definition.

Co-Authored-By: Claude Sonnet 5 <[email protected]>